home *** CD-ROM | disk | FTP | other *** search
/ 130 MIDI Tool Box / 130 MIDI Tool Box.iso / sda_ur22 / sda_user.doc < prev    next >
Text File  |  1988-05-10  |  9KB  |  269 lines
  1.         Software User Interface to the Promidi System, SDA-200.
  2.  
  3.                     Systems Design Associates, Inc.
  4.                      5068 Plano Parkway, Suite 121
  5.                             Plano, TX 75075
  6.                              214/ 248-8530
  7.  
  8.  
  9. Revision: 1.0                   TSR access to the Midicard(tm)
  10. Release Date:     11-11-86
  11. Software: D 1.0 and above.
  12.  
  13. Revision: 2.0                   adds freestanding UART access
  14. Release Date:     07-29-87
  15. Software: D 1.1 and above.
  16.  
  17. Revision: 2.1                   adds UART capability to the TSR mode
  18. Release Date: 10-22-87
  19. Software: D 1.2 and above
  20.  
  21. Revision: 2.2
  22. Release Date: 04-19-88        Added support for 16MZ AT's.
  23. Software: D 1.2 and above    Added MPU mode support for Midicard Expander
  24.  
  25.  
  26.  
  27.              ***************** NOTICE ********************
  28.  
  29. To use the stand-alone routines, a Z8.HEX file dated 7-29-87 or later
  30. must be substituted for any earlier one. Such newer Z8.HEX files are
  31. compatible with all versions of Promidi.  To use UART in the TSR mode
  32. the Z8.HEX must be dated 10-22-87 or later.
  33.  
  34. Systems Design Associates, Inc. Z8.HEX files are NOT in the Public Domain.
  35. All Z8.HEX files are a product part of the Promidi System.
  36.  
  37. The furnishing to any independent developer of any such component part of
  38. the Promidi System by SDA or its authorized representatives, should such be
  39. done, is intended only as a convenience to such independent developers
  40. and in no way abrogates the rights, commercial or otherwise, of Systems
  41. Design Associates, Inc.
  42.  
  43. The source files 'SDA_USR1.ASM'and SDA_USR2.ASM are provided free of
  44. charge by Systems Design Associates, Inc.  SDA in no way warrants
  45. this software nor is it liable for any damages resulting from its use.
  46.  
  47. The use of these routines by any independent developer signifies that he
  48. understands and agrees to these conditions and limitations.
  49.  
  50.              *********************************************
  51.  
  52.  
  53. This document is intended to describe the Promidi Software User
  54. Interface as it pertains to memory resident and stand-alone software.
  55. Both this document and the accompanying source files of IBM assembly
  56. language subroutines (SDA_USR1.ASM and SDA_USR2.ASM), are in the
  57. public domain.  This growing collection of subroutines is intended
  58. to provide designers access into a running Promidi system (in the
  59. case of TSR software) or the Midicard interface (in the case of
  60. stand-alone software).
  61.  
  62. The first part of this document is intended to provide specific
  63. information to designers who are already familiar with IBM-PC
  64. "Terminate-and-Stay-Resident" software design.
  65.  
  66. The second part provides information on the software in "SDA_USR2.ASM".
  67. This software will communicate with the Midicard interface directly,
  68. without Promidi software being in memory.
  69.  
  70.  
  71. The subroutines in 'SDA_USR1.ASM' and 'SDA_USR2.ASM', while provided
  72. in IBM MASM assembler format, are callable as C Functions when
  73. linked with Microsoft C (versions 3.0 and greater) modules.  Whether called
  74. from C or assembler language, they are FAR routines.  If NEAR calls
  75. are desired, or if for instance the designer wishes to pass and return
  76. parameters differently, the source may be modified accordingly.
  77.  
  78.  
  79.  
  80. PART 1
  81.  
  82.                 TERMINATE AND STAY RESIDENT SOFTWARE SUPPORT.
  83.  
  84. Memory Resident Software Requirements.
  85.  
  86.   PC-DOS (MS-DOS) 2.0 or later is required.
  87.  
  88.   384 K. Bytes (plus the memory necessary for the resident software) is
  89.   required.
  90.  
  91.   The software should be installed before Promidi is run.
  92.  
  93.   The software should get control by intercepting INT 16 (The keyboard
  94.   I/O call) and looking for an ALT key (Promidi does not use ALT keys),
  95.   but only if AH is 0, that is, Promidi is actually reading (not
  96.   testing for) a keystroke.
  97.  
  98.   Promidi does not use graphics modes in any of its screens, therefore
  99.   saving the screens is relatively straightforward.  In the future, SDA
  100.   intends to provide a general-purpose 'screen redraw' subroutine to be
  101.   used at the end of the user interrupt.
  102.  
  103.   The software should return the ALT key to Promidi at the end of the
  104.   interrupt.  If this is not done, upon returning to Promidi, the user
  105.   will have to hit an "extra" keystroke.
  106.  
  107.   The software should also exit with interrupts enabled, else a "red
  108.   switch" restart will be required.
  109.  
  110.   Calls into Promidi require only 40 bytes of user stack space
  111.   (maximum).  Promidi's stacks are used for all operations.
  112.  
  113.  
  114. Saving Promidi's Data Segment (DS register).
  115.  
  116. Upon each entrance to the memory resident software (through INT 16),
  117. when saving Promidi's context, the contents of Promidi's DS register
  118. must be saved in '_SDA_DSEG' (public in SDA_USR1.ASM).
  119.  
  120. Checking for The Midicard Interface.
  121.  
  122. Upon each entrance to the memory resident software (through INT 16), the
  123. subroutine '_CHECK4_SDA' must be called SUCCESSFULLY.  This routine
  124. performs two functions:
  125.  
  126.   1. It tests for and locates a running SDA Midicard Interface.
  127.   2. It run-time binds the memory resident software to Promidi.
  128.  
  129. If this routine does not complete successfully (see subroutine header in
  130. 'SDA_USR1.ASM'), no other Promidi subroutines should be called.
  131.  
  132.  
  133.  
  134. SDA_USR1.ASM  -  LIST OF USER SUBROUTINES.
  135.  
  136. Output.
  137.  
  138.   _SDA_PUTB  -  Send a byte (of a complete Midi message) out Midi Out.
  139.  
  140.  
  141. Input.
  142.  
  143.   _SDA_RECON  -  Go into record mode.
  144.  
  145.     This routine must be called before any input can be received via
  146.     the Midicard Interface.  It has three functions:
  147.  
  148.  
  149.       1. It checks to see if Promidi is currently recording.  If so, no
  150.          user recording can be done.
  151.  
  152.       2. It allocates a record buffer within Promidi (the number of
  153.          bytes are returned from the call).  This buffer will usually
  154.          be about 40K bytes.
  155.  
  156.       3. It tells the Midicard to start sending data to Promidi.
  157.  
  158.  
  159.   _SDA_RECOFF  -  Leave record mode.
  160.  
  161.     This routine must be called (if _SDA_RECON was called) before the
  162.     memory resident software terminates (returns from INT16).
  163.  
  164.     ** Failure to do so will result in the loss of the record buffer. **
  165.  
  166.  
  167.   _SDA_GETB  -  Get a byte of a complete Midi message from the record
  168.                 buffer.
  169.  
  170.  
  171. General.
  172.  
  173.   _SDA_EXEC  -  Runs other Promidi Tasks.
  174.  
  175.     If the memory resident software needs to run while Promidi is
  176.     recording and/or playing, frequent calls to _SDA_EXEC are necessary
  177.     to keep the record playback process 'alive'.  A call every 15 or 20
  178.     milliseconds is usually sufficient to keep the Midicard supplied
  179.     with data (playback).
  180.  
  181.  
  182.  
  183. Notes on The TSR Environment.
  184.  
  185. Promidi only reads keyboard characters (INT 16, AH=0) from one of its
  186. tasks.  The memory resident software, even though it accessed as an
  187. interrupt, becomes an extension of that task when it uses Promidi
  188. services via the SDA_USER subroutines.  That task does not do disk I/O.
  189. To keep disk I/O active during Promidi's record or playback, calls to
  190. _SDA_EXEC are required.
  191.  
  192.  
  193.  
  194. PART 2
  195.  
  196.                  STAND-ALONE SOFTWARE FOR THE MIDICARD.
  197.  
  198. The stand-alone software in SDA_USR2.ASM is intended to provide access to
  199. a downloaded Systems Design Midicard so it may be used in UART mode.
  200. The Midicard will then send all send all data received from Midi IN to
  201. the host PC and will send all data from the host out MIDI OUT.  There is
  202. no direct flow of data from MIDI IN to MIDI OUT (MIDI THRU) in the
  203. Midicard in UART mode. THRU capabilities must be handled by the host in
  204. this mode.
  205.  
  206. These routines are NOT designed to be memory resident with a running
  207. Promidi system.  Routines that provide services for memory co-resident
  208. software (TSR) are provided as public domain 8086 assembly source in
  209. "SDA_USR1.ASM".
  210.  
  211. The following requirements must be satisfied before data may be sent
  212. and received from a Midicard:
  213.  
  214.  
  215.         1. The Midicard must be downloaded.
  216.  
  217.         The loader program is MLOAD.EXE and the Midicard's software
  218.         is in file Z8.HEX.  Both of these programs are supplied with
  219.         with every Promidi System.  Before Promidi can run, the
  220.         command line "MLOAD Z8" is executed (from BATCH file SDA.BAT).
  221.         Once the Midicard's program has been downloaded, it is intact
  222.         until the PC is powered down.  The same "MLOAD Z8" may be used
  223.         in any batch file to download the Midicard.
  224.  
  225.  
  226.         2. The Midicard must be located and initialized.
  227.  
  228.         A file called SDA.CFG must be in the same directory as MLOAD.EXE
  229.         and Z8.HEX.  This file contains (along with other data) the
  230.         switch settings set by the user at installation to position the
  231.         card in the PC's I/O space and assign it one of four interrupt
  232.         addresses.
  233.  
  234.         The provided routine "_U_LOC_MC" is used to locate and init.
  235.         the Midicard.
  236.  
  237. After these requirments have been satisfied, the I/O routines may be called.
  238.  
  239. Before terminating, the software should ALWAYS call _U_EXIT which will reset
  240. (deactivate) the Midicard.
  241.  
  242.  
  243.  
  244. SDA_USR2.ASM  -  LIST OF USER SUBROUTINES.
  245.  
  246. Output.
  247.  
  248.   _U_SNDB  -  Send a byte out MIDI Out.
  249.  
  250.  
  251.  
  252. Input.
  253.  
  254.   _U_RCVB  -  Get a byte from MIDI In.
  255.  
  256.   _U_TRCV  -  Test for a byte from MIDI In.
  257.  
  258.  
  259.  
  260. Entry.
  261.  
  262.   _U_LOC_MC  -  Locates and initializes the Midicard.
  263.  
  264.  
  265.  
  266. Exit.
  267.  
  268.   _U_EXIT  -  Resets the Midicard on program termination.
  269.